<html>
    <head>
        <style>
            body {
              max-width: 600px;
              margin: 50px auto;
              font-family: Arial;
              font-size: 15px;
              line-height: 1.5em;
            }
            .tip {
              font-size: .8em;
            }
        </style>
    </head>
    <body>
<h1>Validator</h1>

<p>The Validator plugin runs a set of callbacks to determine if a command is valid. This is useful
for checking if a certain action in your diagram does not lead to an invalid state of the diagram 
(from the your application specific perspective).</p>

<h2>Install</h2>

<p>Include <code>joint.dia.commander.js</code> and <code>joint.dia.validator.js</code> to your HTML:</p>
<pre><code>
&lt;script src="joint.dia.command.js" type="text/javascript" &gt;&lt;/script&gt;
&lt;script src="joint.dia.vaidator.js" type="text/javascript" &gt;&lt;/script&gt;
</code></pre>

<h2>Creating a validator</h2>

<pre><code>
var graph = new joint.dia.Graph;
var paper = new joint.dia.Paper({
    el: $('#paper'),
    width: 500,
    height: 500,
    gridSize: 1,
    model: graph
});

var commandManager = new joint.dia.CommandManager({ graph: graph });

<strong>var validator = new joint.dia.Validator({ graph: graph });</strong>

validator.validate("remove", function(err, command, next) {
  if (command.data.type === 'basic.Rect') return next('Rectangles can't be removed.');
  return next();
}, function(err, command, next) {
  if (err) console.log(err);
  return next(err);
});

</code></pre>

<p>(Those that know the great <a href="http://expressjs.com">ExpressJS</a> application framework might have
recognized a similar API to what ExpressJS provides for registering URL route handlers.)</p>

<h2>Validator API</h2> 

<h3>constructor</h3>

<p>The <code>joint.dia.Validator</code> constructor takes two parameters.</p> 

<h4>commandManager</h4>
<p>The command manager the validator listens to.</p>

<h4>cancelInvalid</h4>
<p>Determine whether to cancel an invalid command or not. If set to <code>false</code>, only the <code>invalid</code> event is triggered.</p>
<p>Default is <code>true</code>.</p>
<p></p>

<h3>validate</h3>

<p>Function <code>validate(action [, callback]*)</code> registers callbacks for a given action.</p>

<p> The validator listens on commands added to the command manager and runs a set of callbacks registered for the <code>action</code>. Callbacks are routed the same way as you might know from ExpressJS. If the last callback returns an error the command is canceled (see <code>joint.dia.CommandManager.cancel()</code>). This behaviour can be supressed by setting the <code>cancelInvalid</code> to <code>false</code> in options passed to the Validator constructor.</p>

<h4>action</h4>
Action is a name of the Backbone model event. Multiple actions may be given seperated by whitespaces.

<pre><code>
validate("change:source change:target", function() { .. });
</pre></code>

<h4>callback</h4>
<p>Multiple callbacks may be given. All callbacks are treated equally. Every callback function should have the following signature:</p>

<pre><code>callback(err, command, next)</code></pre>

<p>Where <code>err</code> is the error from the previous callback.</p>
<p>The <code>command</code> parameter is a record from the command manager stack. It holds information about an action in the graph.</p>
<p>See below for the structure of a <code>command</code>. This command says that a <code>basic.Rect</code> element has been moved by 50px down.</p>
<pre><code>
{
  "action" : "change:position"
  "data": {
    "id":"e0552cf2-fb05-4444-a9eb-3636a4589d64", // id of the cell it was manipulated with
    "type":"basic.Rect", // type of the cell

    // change:attribute events have always these two attributes filled
    "previous": { "position":{"x":50,"y":50} },
    "next": { "position": {"x":50,"y":100}},
  },
  "batch":true, // is command part of a batch command?
  "options":{} // Backbone options that are passed through the listeners when passed as the last argument to the Backbone Model set() method.
}
</code></pre>

<p>The <code>add</code> and <code>remove</code> actions have <code>previous</code> and <code>next</code> object empty. They hold all the cell attributes in the <code>attributes</code> object so that the command manager is able to reconstruct the whole cell if it has to. See below
for an example of such a command structure:</p>

<pre><code>
{
  "action": "add",
  "data" : {
    "id" : "28de715b-62a7-4130-a729-1bcf7dbb1f2b",
    "type":"basic.Circle",

    //empty attributes
    "previous":{},
    "next":{},

    // all cells attributes
    "attributes": {
      "type":"basic.Circle",
      "size": {
        "width":50,
       "height":30
      },
     "position":{"x":1220,"y":680},
     "id":"28de715b-62a7-4130-a729-1bcf7dbb1f2b",
     "attrs" : {
       "circle" : {
         "width":50,
         "height":30
       }
     }
  "batch":true,
  "options" : {
    "add":true,
    "merge":false,
    "remove":false
  }
}
</code></pre>

<p>The <code>next</code> parameter is a function accepting one argument - an error passed to the next callback in row.</p>
Calling <code>next()</code> function means going to the next callback in the order passed to the <code>validate()</code> method. 
If a call to the <code>next()</code> function is omitted, the validation for the specified action stops.</p>
